\manpage intro(2)

\manname
	intro --- introduction to halo emulation library
\mandscr
	The halo emulation library is a collection of routines that
	emulate some of the most frequently used routines of the
	popular HALO graphics library. It was written to assist in
	converting HALO programs to the Grafix library.

	To use the halo functions, you should include the
	file \bfwd halo.h at the start of your program and
	link with the graphics library as usual.

	Most of these functions are fairly straightforward; however,
	there are a few things you should be aware of. First of
	all, and probably most important, all the parameters to all
	the halo routines must be passed by reference, i.e., you must pass
	pointers to the desired arguments to the graphics routines, not
	the arguments themselves. Second, the halo routines
	remember one point, called the graphics cursor, and
	a color, called the current drawing color. The halo
	drawing routines use these values instead of explicitly
	passed parameters in many instances. They may be set with
	the \itnc movabs , \itnc movrel , and \itwd setcolor functions.
	And third, the halo drawing routines always take
	world coordinates, never device coordinates (as is
	possible in the original HALO library).
\manex
\vinput grafex2.c
\manpend

\manpage box(2)

\manname
	box --- draw a rectangular box
\mansyn
	void box(x1, y1, x2, y2)

	float *x1, *y1, *x2, *y2;
\mandscr
	The \itwd box function draws the rectangular box defined by the points
	\itpnt (*x1, *y1) and \itpnt (*x2, *y2) (in world coordinates)
	in the current drawing buffer with the current drawing color.
	If xor mode is on, the rectangle is logically xor'ed with the
	existing data in the buffer.
\mansee
	g_box(1).
\manpend

\manpage cir(2)

\manname
	cir --- draw a circle
\mansyn
	void cir(r)

	float *r;
\mandscr
	The \itwd g_cir function draws a circle centered on the current
	graphics cursor with radius~\itwd r (in world coordinates).
	The circle is drawn in the current drawing buffer with the current
	drawing color. If xor mode is
	on, the circle is logically xor'ed with the existing data in the
	buffer. The radius is taken to be half of the horizontal diameter
	of the circle, in world coordinates.
\mansee
	g_circle(1).
\manpend

\manpage coordinates(2)

\manname
	coordinates --- coordinate systems used
\mandscr
	The halo routines utilize three different coordinate
	systems: device, normalized device, and world. The following
	sections explain these coordinate systems and their
	interrelationships.

\manhead Device coordinates\par

	The first and simplest coordinate system is device coordinates.
	In device coordinates, the origin is at the upper left
	corner of the screen and the axes are scaled in pixels.
	Thus in the four-color mode of the CGA, for example,
	device coordinates range from (0, 0) to (319, 199).
	All the graphics routines listed in section 1 of this manual
	use device coordinates.
	Device coordinates are always expressed as integers.

\vskip\baselineskip
\centerline{\vbox{%
  \hbox to 4in{(0, 0)\hfill (319, 0)}%
  \smallskip
  \hrule width4in
  \hbox to 4in{\vrule height3in
               \hfill
               \vbox to 3in{\vfill\hbox{Device coordinates}\vfill}%
               \hfill
               \vrule height3in}%
  \hrule width4in
  \smallskip
  \hbox to 4in{(0, 199)\hfill (319, 199)}%
}}
\bigskip

\manhead Normalized device coordinates\par

	In normalized device coordinates, the origin is still the
	upper left corner of the screen, but the point (1.0, 1.0)
	is fixed at the lower right corner. This allows one to specify
	coordinates without knowing the physical size of the screen.
	Normalized device coordinates are always expressed as floats.

\vskip\baselineskip
\centerline{\vbox{%
  \hbox to 4in{(0.0, 0.0)\hfill (1.0, 0.0)}%
  \smallskip
  \hrule width4in
  \hbox to 4in{\vrule height3in
               \hfill
               \vbox to 3in{\vfill\hbox{Normalized device coordinates}\vfill}%
               \hfill
               \vrule height3in}%
  \hrule width4in
  \smallskip
  \hbox to 4in{(0.0, 1.0)\hfill (1.0, 1.0)}%
}}
\bigskip

\manhead World coordinates\par

	In world coordinates you can set up a coordinate system
	with an arbitrary offset and scale. For example, if you
	want to have the x coordinates range from $-100$ to $+100$
	and the y coordinates range from $-50$ to $+50$, you would
	call the \itwd setworld function as follows:
\mancodebeg
	  x1 = -100.0;		/* lower left corner */
	  y1 = -50.0;
	  x2 = 100.0;		/* upper right corner */
	  y2 = 50.0;
	  setworld(&x1, &y1, &x2, &y2);
\mancodeend
	This sequence results in the following situation:

\vskip\baselineskip
\centerline{\vbox{%
  \hbox to 4in{($-$100.0, 50.0)\hfill (100.0, 50.0)}%
  \smallskip
  \hrule width4in
  \hbox to 4in{\vrule height3in
               \hfill
               \vbox to 3in{\vfill\hbox{World coordinates}\vfill}%
               \hfill
               \vrule height3in}%
  \hrule width4in
  \smallskip
  \hbox to 4in{($-$100.0, $-$50.0)\hfill (100.0, $-$50.0)}%
}}
\bigskip

\manhead Coordinate transformations\par

	The following routines are available for converting points
	from one coordinate system to another:
{\obeylines
	  mapdton --- convert device to normalized device coordinates
	  mapdtow --- convert device to world coordinates
	  mapntod --- convert normalized device to device coordinates
	  mapntow --- convert normalized device to world coordinates
	  mapwtod --- convert world to device coordinates
	  mapwton --- convert world to normalized device coordinates
}

\manhead Viewports\par

	Viewports allow one to draw only on a portion of the screen.
	For example, if we wanted the same coordinate system as
	we had in the last example but we wanted to use only the
	upper left corner of the screen, we could use:
\mancodebeg
	  x1 = 0.0;   /* upper left corner of viewport in NDC */
	  y1 = 0.0;
	  x2 = 0.5;   /* lower right corner of viewport in NDC */
	  y2 = 0.5;
	  c = -1;     /* no border or clearing */
	  setviewport(&x1, &y1, &x2, &y2, &c, &c);

	  x1 = -100.0;  /* lower left corner */
	  y1 = -50.0;
	  x2 = 100.0;   /* upper right corner */
	  y2 = 50.0;
	  setworld(&x1, &y1, &x2, &y2);
\mancodeend
	This results in the following:

\vskip\baselineskip
\centerline{\vbox{%
  \hbox to 4in{($-$100.0, 50.0)\hfill \hbox to 2in{(100.0, 50.0)\hfill}}%
  \smallskip
  \hrule width 4in
  \hbox to 4in{%
    \vrule height 3in
    \vbox to 3in{%
      \hbox to 2in{%
        \hfill
        \vbox to 1.5in{%
          \vfill
          \hbox{\hfill Viewport\hfill}%
          \vfill
        }%
        \hfill
        \vrule height 1.5in
      }%
      \hrule width 2in
      \smallskip
      \hbox to 2in{($-$100.0, $-$50.0)\hfill}%
      \vfill
    }%
    \vbox to 3in{%
      \vskip 1.5in
      \smallskip
      \hbox{(100.0, $-$50.0)\hfill}%
      \vfill
    }%
    \hfill
    \vrule height 3in
  }%
  \hrule width 4in
}}
\bigskip

	Note that the viewport corners are specified using normalized
	device coordinates.
\mansee
	mapdton(2),
	mapdtow(2), mapntod(2), mapntow(2), mapwtod(2),
	mapwton(2), \hint setworld(2), setviewport(2).
\manpend

\manpage halo_init(2)

\manname
	halo_init --- initialize the halo routines
\mansyn
	void halo_init()
\mandscr
	The \itwd halo_init function initializes the halo routines,
	resets the viewport to the entire screen, and resets world
	coordinates to device coordinates (i.e., x coordinates
	range from 0 to the x size of the device, similarly for
	y coordinates). It also moves the graphics cursor
	to~(0, 0) and sets the current drawing color to~0.
	This function must be called \itwd after
	every call to \itwd g_open and \itwd before any
	other halo routines are used.
\mansee
	g_open(1).
\manpend

\manpage lnabs(2)

\manname
	lnabs ---  draw a line to a specified point
\mansyn
	void lnabs(x, y)

	float *x, *y;
\mandscr
	The \itwd lnabs function draws a line from the current graphics
	cursor position to the point~\itpnt (*x, *y) in world coordinates and
	the graphics cursor is set to~\itpnt (*x, *y). The line is
	drawn in the current drawing buffer with the current drawing
	color. If xor mode is on the line is logically xor'ed with
	the existing data in the buffer.
\mansee
	g_line(1), lnrel(2).
\manpend

\manpage lnrel(2)

\manname
	lnrel --- draw a line relative to the current graphics cursor position
\mansyn
	void lnrel(dx, dy)

	float *dx, *dy;
\mandscr
	The \itwd lnrel function draws a line from the current graphics
	cursor to the point \break \itpnt ({cur_x + *dx}, {cur_y + *dy}) in
	world coordinates, where \itpnt (cur_x, cur_y) is the current
	position of the graphic cursor. After the line is drawn,
	the graphics cursor is moved to \itpnt ({cur_x + *dx},
	{cur_y + *dy}). The line is
	drawn in the current drawing buffer with the current drawing
	color. If xor mode is on the line is logically xor'ed with
	the existing data in the buffer.
\mansee
	g_line(1), lnabs(2).
\manpend

\manpage mapdton(2)

\manname
	mapdton --- map device to normalized device coordinates
\mansyn
	void mapdton(dx, dy, nx, ny)

	int *dx, *dy;
	float *nx, *ny;
\mandscr
	The \itwd mapdton function converts the device coordinates
	\itpnt (*dx, *dy) to the corresponding normalized device
	coordinates \itpnt (*nx, *ny).
\mansee
	coordinates(2),
	mapdtow(2), mapntod(2), mapntow(2), mapwtod(2),
	mapwton(2), setworld(2), setviewport(2).
\manpend

\manpage mapdtow(2)

\manname
	mapdtow --- map device to world coordinates
\mansyn
	void mapdtow(dx, dy, wx, wy)

	int *dx, *dy;
	float *wx, *wy;
\mandscr
	The \itwd mapdtow function converts the device coordinates
	\itpnt (*dx, *dy) to the corresponding world
	coordinates \itpnt (*wx, *wy).
\mansee
	coordinates(2),
	mapdton(2), mapntod(2), mapntow(2), mapwtod(2),
	mapwton(2), setworld(2), setviewport(2).
\manpend

\manpage mapntod(2)

\manname
	mapntod --- map normalized device to device coordinates
\mansyn
	void mapntod(nx, ny, dx, dy)

	float *nx, *ny;
	int *dx, *dy;
\mandscr
	The \itwd mapntod function converts the normalized device coordinates
	\itpnt (*nx, *ny) to the corresponding device
	coordinates \itpnt (*dx, *dy).
\mansee
	coordinates(2),
	mapdton(2), mapdtow(2),  mapntow(2), mapwtod(2),
	mapwton(2), setworld(2), setviewport(2).
\manpend

\manpage mapntow(2)

\manname
	mapntow --- map normalized device to world coordinates
\mansyn
	void mapntow(nx, ny, wx, wy)

	float *nx, *ny;
	float *wx, *wy;
\mandscr
	The \itwd mapntow function converts the normalized device coordinates
	\itpnt (*nx, *ny) to the corresponding world
	coordinates \itpnt (*wx, *wy).
\mansee
	coordinates(2),
	mapdton(2), mapdtow(2), mapntod(2), mapwtod(2),
	mapwton(2), setworld(2), setviewport(2).
\manpend

\manpage mapwtod(2)

\manname
	mapwtod --- map world to device coordinates
\mansyn
	void mapwtod(wx, wy, dx, dy)

	float *wx, *wy;
	int *dx, *dy;
\mandscr
	The \itwd mapwtod function converts the world coordinates
	\itpnt (*wx, *wy) to the corresponding device
	coordinates \itpnt (*dx, *dy).
\mansee
	coordinates(2),
	mapdton(2), mapdtow(2), mapntod(2), mapntow(2),
	mapwton(2), setworld(2), setviewport(2).
\manpend

\manpage mapwton(2)

\manname
	mapwton --- map world to normalized device coordinates
\mansyn
	void mapwton(wx, wy, nx, ny)

	float *wx, *wy;
	float *nx, *ny;
\mandscr
	The \itwd mapwton function converts the world coordinates
	\itpnt (*wx, *wy) to the corresponding normalized device
	coordinates \itpnt (*nx, *ny).
\mansee
	coordinates(2),
	mapdton(2), mapdtow(2), mapntod(2), mapntow(2), mapwtod(2),
	setworld(2), setviewport(2).
\manpend

\manpage movabs(2)

\manname
	movabs --- move the graphics cursor to a specified point
\mansyn
	void movabs(x, y)

	float *x, *y;
\mandscr
	The \itwd movabs function moves the graphics cursor to the
	position \itpnt (*x, *y) in world coordinates.
\mansee
	movrel(2).
\manpend

\manpage movrel(2)

\manname
	movrel --- move the graphics cursor relatively
\mansyn
	void movrel(dx, dy)

	float *dx, *dy;
\mandscr
	The \itwd movrel function moves the graphics cursor to the
	position \itpntb ({cur_x + *dx}, {cur_y + *dy}) in world
	coordinates where \itpnt (cur_x, cur_y) is the current position
	of the graphics cursor.
\mansee
	movabs(2).
\manpend

\manpage setcolor(2)

\manname
	setcolor --- set the current drawing color
\mansyn
	void setcolor(c)

	int *c;
\mandscr
	The \itwd setcolor function sets the current drawing color
	to~\itnc c . If~\itwd c is greater than the maximum color
	value available on the graphics device in use, the
	maximum value is used instead.
\manpend

\manpage setviewport(2)

\manname
	setviewport --- set the active viewport
\mansyn
	void setviewport(x1, y1, x2, y2, border, backgnd)

	float *x1, *y1, *x2, *y2;
	int *border, *backgnd;
\mandscr
	The \itwd setviewport function sets the viewport and the
	clipping boundaries to the rectangular area defined by the
	points \itpnt (x1, y1) and \itpnt (x2, y2) in normalized device
	coordinates. If \itwd border is not $-$1, a border of
	color~\itwd border will be drawn around the viewport (if there is
	room for it), and if~\itwd backgnd is not $-$1, the interior
	of the viewport will be cleared to color~\itnc backgnd .
\mansee
	g_setclip(1), coordinates(2), setworld(2).
\manpend

\manpage setworld(2)

\manname
	setworld --- set world coordinates
\mansyn
	void setworld(x1, y1, x2, y2)

	float *x1, *y1, *x2, *y2;
\mandscr
	The \itwd setworld function changes the current world coordinate
	system. The world coordinates of the lower left corner of
	the viewport become \itpnt (x1, y1), and the world
	coordinates of the upper right corner of the viewport
	become \itpnt (x2, y2).
\mansee
	coordinates(2), setviewport(2).
\manpend

\manpage setxor(2)

\manname
	setxor --- turn xor mode on or off
\mansyn
	void setxor(flag)

	int *flag;
\mandscr
	The \itwd setxor function turns xor mode on if \itwd~*flag
	is nonzero, or off if \itwd~*flag is zero. When xor mode is
	off, drawn objects are simply written over existing data in
	the drawing buffer. But if xor mode is on, drawn objects
	are logically xor'ed with the existing data. Thus if an object
	is drawn twice in a row in exactly the same position with xor
	mode on, it will be completely erased after the second drawing
	and the image on the
	screen restored to its state previous to the first drawing.
	This makes xor mode useful for animation and other effects.
	Functions which support xor mode are {\it g_box, g_circle,
	g_ellipse, g_line, g_point, box, cir, lnabs,} and \itnc lnrel .
\manpend
